
POGOSHELL V1.0
--------------

INTRO

Pogoshell is a GBA program that lets you browse and handle files
in a ROM filesystem, almost like on a real OS. You simply copy
all files you want (both data files and executable GBA roms)
into a directory, sort it the way you want under subdirectories,
and then create a full binary with the filesystem in using the
provided MAKEFS command.



QUICKSTART

- Add any files you need to the included root directory.
- Run GO.BAT (this creates the BIN and sends it using FL)

 Note: If this doesnt work for you it's propably because FL
 doesn't have the right to access the parallel-port. In that
 case you need to install an utility like "Userport" (can
 be found at http://www.devrs.com/gba/files/userport.zip)

 If you want to use another flash-program (like FAW) just
 send the generated rom.bin with that program instead.

USING

When you start pogoshell the first time a small splash-screen
will appear (you can see it again by pressing R+SELECT). Now
you can start browsing.

Directional Pad - Move marker
A = Enter directory or execute file
B = Back up to parent directory
SELECT = Help screen
START = Switch to SRAM view
L+SELECT = Switch to settings screen
L+A = Exectue rom with reset
R+A = Execute rom with intro-skip (doesn't always work).



SRAM MODE

Pogoshell also handles SRAM. Whenever you run a program or game
that uses SRAM, it will be saved into the sram-filesystem the
next time you start the shell.

Remember to select the bank containing the save-file before
starting your rom the next time.

Directional Pad - Move marker
B = Back up to root
R+A = Copy selected file to clipboard
L+A = Paste selected file from clipboard
L+R+A = Delete selected file
START = Switch between the 3 different banks

If you have a save for a rom that does not have a matching name
it will not be loaded when you execute that rom. To fix this
you can rename the save file in the clipboard to match a
given rom, like this;

- Copy the Save file to the clipboard (R+A in sram view)
- Mark the matching rom in the fileview and press L+A
- Go back to SRAM view, swith to a bank with free space and press
  L+A to paste the file with the new name in that bank

Now you can start the rom and it will load the save file.

NOTE:
In the latest version (v0.95+), savefiles have a new format and
can be found even when they do not have a matching name, as long
as they where saved from the same game.


SETTINGS

The settings screen lets you configure PogoShell. These are the
current options


o Hide known extentions

Hide the extentions of known files (files with icons).

o 2D Icon Layout

2D layout instead of list layout.

o Textviewer fixed font

Use a fixed font for the textviewer instead of proportional.

o Ask before saving

At startup, ask before saving the last execute rom to SRAM
(Otherwise it always loads).

o Ask before loading

Ask before loading the save file for roms you execute from the shell
(Otherwise it always saves).

o Map /sram in filesystem

Show sram like a normal catalog in the root directory.

o Map /settings in filesystem

Show settings like a normal catalog in the root directory.

o Hide dot files

Hide all files beginning with "." - this includes the settings-file
in SRAM (.state) and the .plugins and .shell directories.

o Return from SRAM/Settings

Remembers the previous directory when you enter SRAM view or settings,
and return there when you press B.


Remember that auto-saving but not auto-loading can be dangerous as
you may then save over your old savefile with a new empty save
file (like from the beginning of the game).



SHELL OPERATION

On startup, Pogoshell first loads the fonts (.shell/fixed.font and
.shell/nokia.font), inits the GUI (from .shell/gui.cfg), loads the
texts strings (.shell/texts) and then the filetypes (.shell/filetypes).
These files must therefore always be present.
Then it checks if you executed a rom that used SRAM last time, and
automatically saves that data into a file in the same bank as you
started the rom with.

Notice that Pogoshell uses the 3 last of the 4 sram banks for it's
filessystem, while the first bank is always set when executing a
ROM.

The "filetypes" file maps extensions to icons and filehandlers. It's
still sort of preliminary. The format is:
First line: Default icon
Other lines: <extension> <icon> <handler> <Info text>

If there is no handler, .plugins/<extension>.bin is used, otherwise
the handler is used - unless it's one of the predefined internal
handlers (just TXT, EXE, MB, FNT, SET and SAV for now).

TXT - Textfiles handled by the internal textviewer
EXE - Excutable romimage
MB  - Executable multiboot image
FNT - Font file
SET - Indicates the icon to use in the settings view
SAV - SRAM Save file

<Info Text> is shown in the statusbar when the handler is executed.



PLUGINS

Whenever you click on a file that is not a ROM (.gba or .bin) and
is not handled internally (.mb or .txt), Pogoshell tries to
execute ".plugins/<extension>.bin" with the file you clicked on
as argument(so if you click on a mod-file it tries to run mod.bin).

In this way you can extend the functionality of the shell. Take
a look in the plugins directory for the sourcecode for the bmp
and mod plugins. (The bmpview plugin uses libpogo so you have to
get that from my site).

Modplayer

The modplayer handles normal mods using libafm and mods converted
to CodeWaves format (far better playback) - and you can also
compress them with LZ77 (what GBA bios handles).

- To convert a mod, use MODCONV.EXE included in the CodeWaves SDK
  (Download from http://www.codewaves.com/gbaplay.html)
- To compress, use the included DCMP.EXE program in tools.

The modplayer decides what the file is depending on extension:

- "mod" Normal mod played through libafm
- "mdz" Compressed mod
- "cw" CodeWaves converted mod, played through CodeWaves SDK
- "cwz" Compressed Codewaves mod


Bmpviewer

Primitive, only handles 8bit or 24bit pictures that are 240x160
or less.



THEMES

When Pogoshell starts it looks for ".shell/gui.cfg". If this is
found it uses the settings there to setup the GUI. Look in the
THEME directory for an example. These are the available commands:

tb_height=<n>

Set height of titlebar to n pixels. The first n lines of the
BMP is the titlebar.

sb_height=<n>

Set height of the statusbar to n pixels. The statusbar follows
directly under the titlebar in the BMP. You can set this to 0
meaning the statusbar will not be used.

icon_width=<n>
icon_height=<n>

Set the size of icons. The icons are read from under the
statusbar, from left to right.

num_icons=<n>

Set number of icons used.

icons=<filename>

Sets the BMP picture to use for the GUI. Note that this must
be a 8bit (paletted) BMP using no more than 240 colors (as the
first 16 colors are reserved by the shell).

font=<filename>

Set the font to use.
(If you want to convert new fonts you have to download the pogo
library which contans a MAKEFONT tool).

fgcolor=<n>
bgcolor=<n>

Set the color-number to use as fore- or back-ground color.
Remember that the first 16 colors are reserved by PogoShell
(standard ANSI, white is 15 for instance) so if you want to use
any of the colors from your BMP you have to add 16 to the color
index.

To try out the provided themes, just copy "gui.cfg", "icons.bmp"
and "filetypes" from the theme directory into your "root/.shell"
folder.


ICONS

PogoShell displays an icon for every file, as defined in the
filetypes file. However, if a specific icon-file is placed in
a directory and is called the same as a file in that directory
it will be used instead of the default icon.
If you have for instance the file
Snake.gba
and you put and icon called
.Snake.icon
in the same directory, it will be used.

Icons are created with ICON.EXE <infile> <outfile> where infile
is a 8bit BMP with the same palette as your theme.

The format of icons are very simple; the first byte is width, the
second is height, and then follows width*height bytes of pixels.



OLDER (TURBO) CARTS

I've tried to include support for older carts in MAKEFS but I don't
yet know if it works. use the "-old" switch to build a filesystem
compatible with old carts.

NOTE!

Because of the restrictions of old carts the generated binary may
end up much larger than what will fit on your cart even if the
files are small - there is nothing I can do about this.

The maximum number of roms (executables) you can have in a
128Mbit turbo cart is seven; 3 small romfiles (less than 32KByte)
and 4 large ones (more than 32KByte but less than 3.99 MByte).
Note that this is _max_ - the number will be lower if any of the
files are larger.



-- Sasq (Jonas Minnberg)
jonas@nightmode.org


PS. All of the filesystem stuff etc works through my library "pogo" which
lets you access the added files normally (opedir, readdir, execv etc) -
which you should be able to download now...
